home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / KoSpeaker.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-30  |  8.0 KB  |  205 lines
  1. /** @file
  2. *   This file is part of the KDE/KOffice project.
  3. *   Copyright (C) 2005, Gary Cramblitt <garycramblitt@comcast.net>
  4. *
  5. *   @author Gary Cramblitt <garycramblitt@comcast.net>
  6. *   @since KOffice 1.5
  7. *
  8. *   This library is free software; you can redistribute it and/or
  9. *   modify it under the terms of the GNU Library General Public
  10. *   License as published by the Free Software Foundation; either
  11. *   version 2 of the License, or (at your option) any later version.
  12. *
  13. *   This library is distributed in the hope that it will be useful,
  14. *   but WITHOUT ANY WARRANTY; without even the implied warranty of
  15. *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  16. *   Library General Public License for more details.
  17. *
  18. *   You should have received a copy of the GNU Library General Public License
  19. *   along with this library; see the file COPYING.LIB.  If not, write to
  20. *   the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
  21. *   Boston, MA 02110-1301, USA.
  22. */
  23.  
  24. #ifndef KOSPEAKER_H
  25. #define KOSPEAKER_H
  26.  
  27. // Qt includes.
  28. #include <qobject.h>
  29. #include <qstring.h>
  30.  
  31. // KDE includes.
  32. #include <ksharedptr.h>
  33.  
  34. // KOffice includes.
  35. #include <koffice_export.h>
  36.  
  37. class QWidget;
  38. class QPoint;
  39. class KConfig;
  40. class KoSpeakerPrivate;
  41.  
  42. #define kospeaker KoSpeaker::koSpeaker()
  43.  
  44. /** KoSpeaker is a singleton object that provides Text-to-Speech services for KOffice applications.
  45.   * When activated, it will speak the text of widgets under the mouse pointer and/or the
  46.   * the widget with focus.
  47.   *
  48.   * It also provides some methods for speaking text from documents.
  49.   *
  50.   * IMPORTANT: This class will be removed from KOffice when KOffice is converted to KDE4.
  51.   * It will be replaced with a proper screen reading capability using the AT-SPI.
  52.   *
  53.   * This is quite a hack and doesn't work reliably.  The following are current problems:
  54.   *   1.  Cannot speak menu items in a QMenuBar (top menu of app).
  55.   *   2.  Doesn't understand every possible widget.
  56.   *
  57.   * This capability is @em not intended for completely blind users.  Such users cannot use
  58.   * KDE 3.x anyway, since it lacks a screen reader.  Instead, this capability is intended as
  59.   * an aid to users with other vision disabilities.
  60.   *
  61.   * KOffice applications can access this object using the kospeaker global.
  62.   */
  63. class KOFFICECORE_EXPORT KoSpeaker : public QObject, public KShared
  64. {
  65.    Q_OBJECT
  66. public:
  67.     KoSpeaker();
  68.     ~KoSpeaker();
  69.  
  70.     /** Speech Options */
  71.     enum SpeakFlags {
  72.         SpeakFocusWidget =      0x0001  /**< Speak widget with focus */,
  73.         SpeakPointerWidget =    0x0002  /**< Speak widget under mouse pointer */,
  74.         SpeakWhatsThis =        0x0004  /**< Speak Whats This if available */,
  75.         SpeakTooltip =          0x0008  /**< Speak tooltip if available */,
  76.         SpeakAccelerator =      0x0010  /**< Speak accelerator */,
  77.         SpeakDisabled =         0x0020  /**< Say 'disabled' if not enabled */
  78.     };
  79.  
  80.     /**
  81.      * Returns true if TTS services are available.  If KTTSD daemon is not running, it is started.
  82.      * Will return false if:
  83.      * -- KTTSD daemon is not installed, or
  84.      * -- Was not able to start KTTSD daemon for some reason.
  85.      */
  86.     bool isEnabled() const;
  87.  
  88.     /**
  89.      * Reads configuration options from @p config object and starts TTS if screen reader
  90.      * capability is requested.
  91.      * If KTTSD daemon is not installed, @ref isEnabled will return false.
  92.      * If screen reader is requested and KTTSD is installed, but not running, it will be started.
  93.      */
  94.     void readConfig(KConfig* config);
  95.  
  96.     /**
  97.      * Given a widget @p w and its @p pos screen coordinates, tries to extract the text of the widget
  98.      * and speak it.  If @p pos is not specified, and the widget has multiple parts (such as
  99.      * a QListView), uses the current part.
  100.      * Call @ref isEnabled to ensure TTS is available before calling this method.
  101.      */
  102.     bool maybeSayWidget(QWidget* w, const QPoint& pos = QPoint());
  103.  
  104.     /**
  105.      * Speak a @p msg that came from a widget, such as the widget's text label, tool tip, etc.
  106.      * Speaks using ScreenReaderOutput, which has highest priority, and therefore, should only be
  107.      * be used in very time-sensitive contexts and for short messages.
  108.      * Certain standard substitutions are performed on the message.  For example, "Ctrl+" becomes
  109.      * "control plus".  "Qt" markup is stripped.
  110.      * @returns true if anything is actually spoken.
  111.      * Call @ref isEnabled to ensure TTS is available before calling this method.
  112.      */
  113.     bool sayWidget(const QString& msg);
  114.  
  115.     /**
  116.      * Cancels speaking of widget.  Usually called by slots that receive @ref customSpeakNewWidget
  117.      * signal when they wish to speak the widget themselves.
  118.      */
  119.     void cancelSpeakWidget();
  120.  
  121.     /**
  122.      * Queue a @p msg as a speech text job.  The text is encoded in the @p langCode language.
  123.      * Examples "en", "es", "en_US".  If not specified, defaults to current desktop setting.
  124.      * If @p first is true and a job is already speaking, cancel it.
  125.      * If @p first is false, appends to the already queued job.
  126.      * If the KTTSD daemon is not already running, it is started.
  127.      */
  128.     void queueSpeech(const QString& msg, const QString& langCode = QString(), bool first = true);
  129.  
  130.     /**
  131.      * Start speaking queued text job (if any).
  132.      */
  133.     void startSpeech();
  134.  
  135.     /**
  136.      * Returns whether the KTTSD deamon is installed in the system.  If not, apps should disable
  137.      * or hide options/commands to speak.
  138.      */
  139.     static bool isKttsdInstalled();
  140.  
  141.     /**
  142.      * Returns the KoSpeaker object singleton.  Apps should use "kospeaker" rather than this function
  143.      * directly.
  144.      */
  145.     static KoSpeaker* koSpeaker() { return KSpkr; }
  146.  
  147. signals:
  148.     /**
  149.      * This signal is emitted whenever a new widget has received focus or the mouse pointer
  150.      * has moved to a new widget.  If a receiver wishes to handle speaking of the widget itself,
  151.      * it should call @ref cancelSpeakWidget() .
  152.      * @param w         The widget.
  153.      * @param p         Mouse pointer global coordinates, or in the case of a focus change (0,0).
  154.      * @param flags     Speech options.  @ref SpeakFlags.
  155.      *
  156.      * IMPORTANT: This signal is emitted from the @ref maybeSayWidget method.  Slots who
  157.      * call maybeSayWidget should take care to avoid infinite recursion.
  158.      */
  159.     void customSpeakNewWidget(QWidget* w, const QPoint& p, uint flags);
  160.  
  161.     /**
  162.      * This signal is emitted each polling interval when KoSpeaker did not speak the widget
  163.      * (either because it did not think the widget was a new one or because it did not
  164.      * understand the widget).  If both mouse pointer and focus flags are set, it may
  165.      * emit twice per polling interval.
  166.      * @param w         The widget.
  167.      * @param p         Mouse pointer global coordinates, or in the case of a focus change (0,0).
  168.      * @param flags     Speech options.  @ref SpeakFlags.
  169.      *
  170.      * IMPORTANT: This signal is emitted frequently.  Receivers should be coded efficiently.
  171.      */
  172.     void customSpeakWidget(QWidget* w, const QPoint& p, uint flags);
  173.  
  174. protected:
  175.     static KoSpeaker* KSpkr;
  176.  
  177. private slots:
  178.     /**
  179.      * Tells the class to do it's stuff - ie. figure out
  180.      * which widget is under the mouse pointer or which has focus and speak it.
  181.      */
  182.     void probe();
  183.  
  184. private:
  185.     // int menuBarItemAt(QMenuBar* m, const QPoint& p);
  186.  
  187.     // Start the KTTSD daemon if not already running.
  188.     bool startKttsd();
  189.     // Return the KTTSD daemon version string.
  190.     QString getKttsdVersion();
  191.  
  192.     // These methods correspond to dcop interface in kdelibs/interfaces/kspeech/kspeech.h.
  193.     // They use manual marshalling, instead of using kspeech_stub, because KOffice
  194.     // supports KDE 3.3 and above and kspeech.h didn't appear until 3.4.
  195.     void sayScreenReaderOutput(const QString &msg, const QString &talker);
  196.     uint setText(const QString &text, const QString &talker);
  197.     int appendText(const QString &text, uint jobNum=0);
  198.     void startText(uint jobNum=0);
  199.     void removeText(uint jobNum=0);
  200.  
  201.     KoSpeakerPrivate* d;
  202. };
  203.  
  204. #endif      // H_KOSPEAKER
  205.